

    \filetitle{x12}{Access to X13-ARIMA-SEATS seasonal adjustment program}{tseries/x12}

	\paragraph{Syntax with a single type of output
requested}

\begin{verbatim}
[Y,OutpFile,ErrFile,Model,X] = x12(X,...)
[Y,OutpFile,ErrFile,Model,X] = x12(X,Range,...)
\end{verbatim}

\paragraph{Syntax with mutliple types of output
requested}

\begin{verbatim}
[Y1,Y2,...,OutpFile,ErrFile,Model,X] = x12(X,Range,...)
\end{verbatim}

See the option \texttt{\textquotesingle{}output=\textquotesingle{}} for
the types of output data available from X12.

\paragraph{Input arguments}

\begin{itemize}
\item
  \texttt{X} {[} tseries {]} - Input data that will seasonally adjusted
  or filtered by the Census X12 Arima; \texttt{X} must be a quarterly or
  monthly time series.
\item
  \texttt{Range} {[} numeric \textbar{} char \textbar{} \texttt{@all}
  {]} - Date range on which the X12 will be run; \texttt{@all} means the
  entire on which the input time series is defined; \texttt{Range} may
  be omitted.
\end{itemize}

\paragraph{Output arguments}

\begin{itemize}
\item
  \texttt{Y}, \texttt{Y1}, \texttt{Y2}, \ldots{} {[} tseries {]} -
  Requested output data, by default only one type of output is returned,
  the seasonlly adjusted data; see the option
  \texttt{\textquotesingle{}output=\textquotesingle{}}.
\item
  \texttt{OutpFile} {[} cellstr {]} - Contents of the output log files
  produced by X12; each cell contains the log file for one type of
  output requested.
\item
  \texttt{ErrFile} {[} cellstr {]} - Contents of the error files
  produced by X12; each cell contains the error file for one type of
  output requested.
\item
  \texttt{Model} {[} struct {]} - Struct array with model specifications
  and parameter estimates for each of the ARIMA models fitted;
  \texttt{Model} matches the size of \texttt{X} is 2nd and higher
  dimensions.
\item
  \texttt{X} {[} tseries {]} - Original input data with forecasts and/or
  backcasts appended if the options
  \texttt{\textquotesingle{}forecast=\textquotesingle{}} and/or
  \texttt{\textquotesingle{}backcast=\textquotesingle{}} are used.
\end{itemize}

\paragraph{Options}

\begin{itemize}
\item
  \texttt{\textquotesingle{}backcast=\textquotesingle{}} {[} numeric
  \textbar{} \emph{\texttt{0}} {]} - Run a backcast based on the fitted
  ARIMA model for this number of periods back to improve on the seasonal
  adjustment; see help on the \texttt{x11} specs in the X13-ARIMA-SEATS
  manual. The backcast is included in the output argument \texttt{X}.
\item
  \texttt{\textquotesingle{}cleanup=\textquotesingle{}} {[}
  \emph{\texttt{true}} \textbar{} \texttt{false} {]} - Delete temporary
  X12 files when done; the temporary files are named
  \texttt{iris\_x12a.*}.
\item
  \texttt{\textquotesingle{}log=\textquotesingle{}} {[} \texttt{true}
  \textbar{} \emph{\texttt{false}} {]} - Logarithmise the input data
  before, and de-logarithmise the output data back after, running
  \texttt{x12}.
\item
  \texttt{\textquotesingle{}forecast=\textquotesingle{}} {[} numeric
  \textbar{} \emph{\texttt{0}} {]} - Run a forecast based on the fitted
  ARIMA model for this number of periods ahead to improve on the
  seasonal adjustment; see help on the \texttt{x11} specs in the
  X13-ARIMA-SEATS manual. The forecast is included in the output
  argument \texttt{X}.
\item
  \texttt{\textquotesingle{}display=\textquotesingle{}} {[}
  \texttt{true} \textbar{} \emph{\texttt{false}} {]} - Display X12
  output messages in command window; if false the messages will be saved
  in a TXT file.
\item
  \texttt{\textquotesingle{}dummy=\textquotesingle{}} {[} tseries
  \textbar{} \emph{empty} {]} - User dummy variable or variables (in
  case of a multivariate tseries object) used in X13-ARIMA-SEATS
  regression; the dummy variables must also include values for forecasts
  and backcasts if you request them; the type of the dummy can be
  specified in the option
  \texttt{\textquotesingle{}dummyType=\textquotesingle{}}.
\item
  \texttt{\textquotesingle{}dummyType=\textquotesingle{}} {[}
  \texttt{\textquotesingle{}ao\textquotesingle{}} \textbar{}
  \emph{\texttt{\textquotesingle{}holiday\textquotesingle{}}} \textbar{}
  \texttt{\textquotesingle{}td\textquotesingle{}} {]} - Type of the user
  dummy (which is specified through the option
  \texttt{\textquotesingle{}dummy=\textquotesingle{}}); the three basic
  types of dummies are additive outlier
  (\texttt{\textquotesingle{}ao\textquotesingle{}}), holiday flows
  (\texttt{\textquotesingle{}holiday\textquotesingle{}}), and trading
  days (\texttt{\textquotesingle{}td\textquotesingle{}}); see the
  X13-ARIMA-SEATS or X13-ARIMA documentation for more details (available
  from the U.S.Census Bureau website), look for the section on the
  REGRESSION spec, options `user' and `usertype'.
\item
  \texttt{\textquotesingle{}mode=\textquotesingle{}} {[}
  \emph{\texttt{\textquotesingle{}auto\textquotesingle{}}} \textbar{}
  \texttt{\textquotesingle{}add\textquotesingle{}} \textbar{}
  \texttt{\textquotesingle{}logadd\textquotesingle{}} \textbar{}
  \texttt{\textquotesingle{}mult\textquotesingle{}} \textbar{}
  \texttt{\textquotesingle{}pseudoadd\textquotesingle{}} \textbar{}
  \texttt{\textquotesingle{}sign\textquotesingle{}} {]} - Seasonal
  adjustment mode (see help on the \texttt{x11} specs in the
  X13-ARIMA-SEATS manual);
  \texttt{\textquotesingle{}auto\textquotesingle{}} means that series
  with only positive or only negative numbers will be adjusted in the
  \texttt{\textquotesingle{}mult\textquotesingle{}} (multiplicative)
  mode, while series with combined positive and negative numbers in the
  \texttt{\textquotesingle{}add\textquotesingle{}} (additive) mode.
\item
  \texttt{\textquotesingle{}maxIter=\textquotesingle{}} {[} numeric
  \textbar{} \emph{\texttt{1500}} {]} - Maximum number of iterations for
  the X12 estimation procedure. See help on the \texttt{estimation}
  specs in the X13-ARIMA-SEATS manual.
\item
  \texttt{\textquotesingle{}maxOrder=\textquotesingle{}} {[} numeric
  \textbar{} \emph{\texttt{{[}2,1{]}}} {]} - A 1-by-2 vector with
  maximum order for the regular ARMA model (can be \texttt{1},
  \texttt{2}, \texttt{3}, or \texttt{4}) and maximum order for the
  seasonal ARMA model (can be \texttt{1} or \texttt{2}). See help on the
  \texttt{automdl} specs in the X13-ARIMA-SEATS manual.
\item
  `missing=' {[} \texttt{true} \textbar{} \emph{\texttt{false}} {]} -
  Allow for in-sample missing observations, and fill in values predicted
  by an estimated ARIMA process; if \texttt{false}, the seasonal
  adjustment will not run and a warning will be thrown.
\item
  \texttt{\textquotesingle{}output=\textquotesingle{}} {[} char
  \textbar{} cellstr \textbar{}
  \emph{\texttt{\textquotesingle{}SA\textquotesingle{}}} {]} - List of
  requested output data; the cellstr or comma-separated list can combine
  any number of the request specifications listed below in subsection
  Output request; See also help on the \texttt{x11} specs in the
  X13-ARIMA-SEATS manual.
\item
  \texttt{\textquotesingle{}saveAs=\textquotesingle{}} {[} char
  \textbar{} \emph{empty} {]} - Name (or a whole path) under which
  X13-ARIMA-SEATS output files will be saved.
\item
  \texttt{\textquotesingle{}specFile=\textquotesingle{}} {[} char
  \textbar{} \emph{\texttt{\textquotesingle{}default\textquotesingle{}}}
  {]} - Name of the X13-ARIMA-SEATS spec file; if
  \texttt{\textquotesingle{}default\textquotesingle{}} the IRIS default
  spec file will be used, see description.
\item
  \texttt{\textquotesingle{}tdays=\textquotesingle{}} {[} \texttt{true}
  \textbar{} \emph{\texttt{false}} {]} - Correct for the number of
  trading days. See help on the \texttt{x11regression} specs in the
  X13-ARIMA-SEATS manual.
\item
  \texttt{\textquotesingle{}tempDir=\textquotesingle{}} {[} char
  \textbar{} function\_handle \textbar{}
  \texttt{\textquotesingle{}.\textquotesingle{}} {]} - Directory in
  which X13-ARIMA-SEATS temporary files will be created; if the
  directory does not exist, it will be created at the beginning and
  deleted at the end of the execution (unless
  \texttt{\textquotesingle{}cleanup=\textquotesingle{}\ false}).
\item
  \texttt{\textquotesingle{}tolerance=\textquotesingle{}} {[} numeric
  \textbar{} \emph{\texttt{1e-5}} {]} - Convergence tolerance for the
  X13 estimation procedure. See help on the \texttt{estimation} specs in
  the X13-ARIMA-SEATS manual.
\end{itemize}

\paragraph{Description}

\subparagraph{Output requests}

The option ``output=' can combine any number of the following requests:

\begin{itemize}
\item
  \texttt{\textquotesingle{}SA\textquotesingle{}} - seasonally adjusted
  series;
\item
  \texttt{\textquotesingle{}SF\textquotesingle{}} - seasonal factors;
\item
  \texttt{\textquotesingle{}TC\textquotesingle{}} - trend-cycle
  component;
\item
  \texttt{\textquotesingle{}IR\textquotesingle{}} - irregular component;
\item
  \texttt{\textquotesingle{}MV\textquotesingle{}} - the original input
  series with missing values fitted by running an estimated ARIMA model.
\end{itemize}

\subparagraph{Missing observations}

If you keep \texttt{\textquotesingle{}missing=\textquotesingle{}\ false}
(this is the default for backward compatibility), \texttt{x12} will not
run on series with in-sample missing observations, and a warning will be
thrown.

If you set \texttt{\textquotesingle{}missing=\textquotesingle{}\ true},
you allow for in-sample missing observations. The X13-ARIMA-SEATS
program handles missing observations by filling in values predicted by
the estimated ARIMA process. You can request the series with missing
values filled in by including \texttt{MV} in the option
\texttt{\textquotesingle{}output=\textquotesingle{}}.

\subparagraph{Spec file}

The default X13-ARIMA-SEATS spec file is
\texttt{+thirdparty/x12/default.spc}. You can create your own spec file
to include options that are not available through the IRIS interface.
You can use the following pre-defined placeholders letting IRIS fill in
some of the information needed (check out the default file):

\begin{itemize}
\tightlist
\item
  \texttt{\$series\_data\$} is replaced with a column vector of input
  observations;
\item
  \texttt{\$series\_freq\$} is replaced with a number representing the
  date frequency: either 4 for quarterly, or 12 for monthly (other
  frequencies are currenlty not supported by X13-ARIMA-SEATS);
\item
  \texttt{\$series\_startyear\$} is replaced with the start year of the
  input series;
\item
  \texttt{\$series\_startper\$} is replaced with the start quarter or
  month of the input series;
\item
  \texttt{\$transform\_function\$} is replaced with \texttt{log} or
  \texttt{none} depending on the mode selected by the user;
\item
  \texttt{\$forecast\_maxlead\$} is replaced with the requested number
  of ARIMA forecast periods used to extend the series before seasonal
  adjustment.
\item
  \texttt{\$forecast\_maxlead\$} is replaced with the requested number
  of ARIMA forecast periods used to extend the series before seasonal
  adjustment.
\item
  \texttt{\$tolerance\$} is replaced with the requested convergence
  tolerance in the \texttt{estimation} spec.
\item
  \texttt{\$maxiter\$} is replaced with the requested maximum number of
  iterations in the \texttt{estimation} spec.
\item
  \texttt{\$maxorder\$} is replaced with two numbers separated by a
  blank space: maximum order of regular ARIMA, and maximum order of
  seasonal ARIMA.
\item
  \texttt{\$x11\_mode\$} is replaced with the requested mode:
  \texttt{\textquotesingle{}add\textquotesingle{}} for additive,
  \texttt{\textquotesingle{}mult\textquotesingle{}} for multiplicative,
  \texttt{\textquotesingle{}pseudoadd\textquotesingle{}} for
  pseudo-additive, or
  \texttt{\textquotesingle{}logadd\textquotesingle{}} for log-additive;
\item
  \texttt{\$x12\_save\$} is replaced with the list of the requested
  output series: \texttt{\textquotesingle{}d10\textquotesingle{}} for
  seasonals, \texttt{\textquotesingle{}d11\textquotesingle{}} for final
  seasonally adjusted series,
  \texttt{\textquotesingle{}d12\textquotesingle{}} for trend-cycle,
  \texttt{\textquotesingle{}d13\textquotesingle{}} for irregular
  component.
\end{itemize}

Two of the placeholders, \texttt{\textquotesingle{}\$series\_data\$} and
\texttt{\$x12\_output\$}, are required; if they are not found in the
spec file, IRIS throws an error.

\subparagraph{Estimates of ARIMA model
parameters}

The ARIMA model specification, \texttt{Model}, is a struct with three
fields:

\begin{itemize}
\item
  \texttt{.spec} - a cell array with the first cell giving the structure
  of the non-seasonal ARIMA, and the second cell giving the structure of
  the seasonal ARIMA; both specifications follow the usual Box-Jenkins
  notation, e.g. \texttt{{[}0\ 1\ 1{]}}.
\item
  \texttt{.ar} - a numeric array with the point estimates of the AR
  coefficients (non-seasonal and seasonal).
\item
  \texttt{.ma} - a numeric array with the point estimates of the MA
  coefficients (non-seasonal and seasonal).
\end{itemize}

\paragraph{Example}

Run X12 on the entire range of a time series:

\begin{verbatim}
xsa = x12(x);
xsa = x12(x,Inf);
xsa = x12(x,@all);
xsa = x12(x,get(x,'range'));
\end{verbatim}


